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af T Lf td 4 = VAX/VMS TEMPLATE DRIVER 
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SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DIGITAL. 
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TAL EQUIPMENT 
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S. Programmer 11-NOV-1979 
REVISION HISTORY: 


v02 JHP001 J. Programmer 2-Aug-1979 11:27 
Remove BLBC instruction from CANCEL routine. 


V02-001 ROWO067 Ralph 0. Weber 11-FEB-1981 13:10 


3+ 

> FACILITY: 

: VAX/VMS Template driver 

> ABSTRACT: 

: This module contains the outline of a driver: 
: Models of driver tables 

3 Controller and unit initialization routines 
: An FDT routine 

3 The start 1/0 routine 

3 The interrupt service routine 

3 The cancel 1/0 routine 

3 The device register dump routine 

: AUTHOR: 


° 
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Add description of reason argument to CANCEL routine. 
Correct references to channel index number. 


2 
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-SBTTL External and local symbol definitions 


: External symbols 


SCANDEF ; Cancel reason codes 

CRBDEF ; Channel request block 

CDEF ; Device classes and types 
SDDBDEF 3; Device data block 
SDEVDEF 3; Device characteristics 
SIDBDEF ; Interrupt data block 
SIODEF ; 1/0 function codes 
SIPLDEF ; Hardware IPL definitions 
SIRPDEF :; 1/0 request packet 

SDEF ; System status codes 
SUCBDEF 3; Unit control block 
SVECDEF ; Interrupt vector block 


: Local symbols 


: Argument List (AP) offsets for device-dependent Q10 parameters 


P1 = 0 ; First Q10 parameter 
P = 4 ; Second Q10 parameter 
P = 8 ; Third Q10 parameter 
P4 = 12 ; Fourth Q10 parameter 
P5 = 16 ; Fifth Q10 parameter 
P6 = 20 ; Sixth Q10 parameter 


: Other constants 


TO_DEF BUFSIZ = 1024 ; Default buffer size 
TO_TIMEOUT SEC = 10 ; 10 second device timeout 
TD_NUM_REGS = 4 ; Device has 4 registers 


: Definitions that follow the standard UCB fields 


SDEFINI UCB ; Start of UCB definitions 

- =UCBSK_LENGTH ; Position at end of UCB 
SDEF UCB$W_TD_WORD num 4 ; A sample word | 
SDEF UCB$W_TD_STATUS am 4 ; Device's CSR register | 
SDEF UCB$W_TD_WRDCNT ; Device’s word count register 


-BLKW 1 


SDEF 
SDEF 
SOEF 


SDEF 
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UCBS$W_TD_BUFADR 
UCBS$W_TD_DATBUF 
UCBSK_TD_UCBLEN 


SVIELD ue 0,<- 


SDEFEND UCB 


SDEFINI TD 
TD_STATUS 


-VIELD 


-BLKW 


TD STS,0,<- 
<66 


<BIT9, .M>.= 
<BIT10,,M>,- 
<BIT11,.M>, ° 


<ATTN, MD, ° 
<NEX,,M>,= 
<ERROR, .>,- 


> 
TD_WRDCNT 

-BLKW 
TD_BUFADR 

-BLKW 
TD_DATBUF 

.BLKW 
SDEFEND TD 


f_2ERO, .M>,- 
ell “ONE, .M>, = 


1 


1 
1 
1 


Device register offsets from CSR address 


: Bit positions for device control/status 


H 
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: pad 4 de : ouffer address 


regist 


; Device® $ data buffer register 
; Length of extended UCB 


Bit positions for device-dependent status field in UCB 


Device status 
First bi 


; Second bit 


; End of UCB definitions 


; Start of status definitions 


Control/status 


register 


ontro!/status register 
art vuevice 


Any address bits 
ble interrupts 
ice ready for command 


ce 
eight 
nine 
ten 
eleven 
regarded bit 
Attention bit 


Nonexistent memory flag 
Error or external interrupt 


C 
St 
Bi 
Bi 
Bit 
Ex 
En 
De 
Bi 
Bi 
Bi 
Bi 
Di 


t 
a 
Vv 
t 
t 
t 
t 
s 


Word count 
Buffer address 
Data buffer 


End of device register 


ae 
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-SBTTL Standard tables 
: Driver prologue table 


DPT 
END=1D END,= 


ADAPTER=UBA, - 
se sate TD_UCBLEN>, = 
DPT_STORE INIT 


DPT S thes use -ucess fie. 
DPT-STORE UCB,UCBS$B “pate 


8 

B 

DPT"STORE UCB; UCBSL- D AR, 
DEVSM_IDv! 


ae ES 
mn 
72 
A 
' 


o 


DEVSM~ODV> 
DPT_STORE UCB;UCB$B_DEVCLASS,B,DC$_SCOM 
DPT~ =STORE UCB, UCB$W-DEVBUFSI2,W,- 
TD_DEF _BUFSTZ 


DPT_STORE REINIT 


DPT_STORE DDB, DDBSL -poT»D TDSDDT 
DPT“STORE CRB,C NIbee D,- 
T Tat ERCUST 
DPT_STORE CRB,- 
CRBSL INTD+VECS$L_INITIAL,- 
D.TD. CONTROL_INIT 
DPT_STORE CR6,- 
CRBSL INTD*VECSL _UNITINIT,= 
D.TD_ONIT_I 


DPT_STORE END 


: Driver dispatch table 


DDTAB = 
AM=TD,= 


CANCEL=TD_ CANCEL ,- 
REGDMP=TD_REG_DUMP 


: Function decision table 
TD_FUNCTABLE: 
FUNCTAB 


<READVBLK, = 
READLBLK, = 


Sete Ge Ge Ge Se 
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DPT=-creation macro 
End of driver label 
Adapter type 

Length of UCB 
Driver a 


sear Cleat 
nitia ot ian table 
Device fork IPL 
Device interrupt IPL 
Device characteristics 
input device 
output device 
Sample device class 
Default buffer size 


Start of reload 
initialization table 
Address of DDT 

Address of interrupt 
service routine 
Address of controller 
initialization routine 


Address of device 
unit initialization 
routine 


End of initialization 
tables 


DDT-creation macro 
Name of device 

Start 1/0 routine 

FDT address 

sence’ 1/0 routine 
Register dump routine 


FDOT for driver 
Valid 1/0 functions 
Read virtual 

Read logical 
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BE APESLK = 3 feed physical ; 
vf VBLK,=- 3; Write rtual $ 
WRITELBLK,= ; Write logical ; 
WRITEPBLK,= ; Write physical $ 
at a ; Set device mode 3 
SETCHAR> ; Set dey ice chars. 3 
FUNCTAB , ; No_ buffered functions 3 
FUNCTAB *+EXESREAD,=- 3; FDOT read routine for ; 
<READVBLK,- : read virtual, : 
READLBLK,=- ; read logical, $ 
READPBLK> ; and read physical. $ 
FUNCTAB +EXESWRITE,- 3; FDT write routine for 
<WRITEVBLK,=- ; write virtual, 
WRITELBLK,=- 3; write logical, 
WRITEPBLK> 3; and write physical. 
FUNCTAB +EXESSETMODE,- 3; FDT set mode routine 
<SETCHAR,= ; for set chars. and 
SETMODE> ; set mode. 
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-SBTTL TD_CONTROL_INIT, Controller initialization routine 


"TD CONTROL_INIT, Readies controller for 1/0 operations 
Functional description: 
The operating system calls this routine in 3 places: 
at system startup 


during driver loading and reloading 
during recovery from a power failure 


Inputs: 
RG - address of the CSR (controller status register) 
RS - address of the IDB (interrupt data block 
R6 - address of the DDB (device data block) 
RB - address of the CRB (channel request block) 
Outputs: 


The routine must preserve all registers except RO-R3. 


TD_CONTROL_ INIT: ; Initialize controller 
RSB ; Return 
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-SBTTL TO_UNIT_INIT, Unit initialization routine 


;++ 
; TOLUNIT_INIT, Readies unit for 1/0 operations 
Functional description: 


The operating system calls this routine after calling the 
controller initialization routine: 


at system startup 
during driver loading 
during recovery from a power failure 


Inputs: 
RG - address of the CSR (controller status register) 
RS - address of the UCB (unit control block) 
Outputs: 


The routine must preserve all registers except RO-R3. 


TD_UNIT_INIT: ; Initialize unit 
ISwW #UCBSM_ONL NE. * 


B I 
UCBSW_STS(RS5 ; Set unit online 
RSB ; Return 
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-SBTTL TD_FDT_ROUTINE, Sample FDT routine 


goo 
; TD_FDT_ROUTINE, Sample FDT routine 


+ 


: Functional description: 


: | 
: T.B.S. é 
: Inputs: ; 

: RO-R2 - scratch registers : 

: RG - address of the PCB (process control block) : 

: R5 - address of the UCB (unit control block) PF 

$ R6 - address of the CCB (channel control block) 3 

: R7 - bit number of the 1/0 function code : 

: R8 - address of the FDT table entry for this routine r 3 

$ R9-R11 = scratch registers : 

: A - address of th» Ist function dependent Q10 parameter : 

: Outputs: = 
: soe, tyeeaae must preserve all registers except RO-R2, and 


TO .FOT_ROUT INE: ; Sample FDT routine 


| 
| 
| 
address of the IRP (1/0 request packet) 
| 
; Return | 


1 
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-SBTTL TO_START, Start 1/0 routine 


+ 
> 


Functional description: 


The routine must preserve all registers except RO-R2 and R4. 


; p++ 
; T.B. ‘« ; Ir 
: Inputs: : 

: Hf - address of the IRP (1/0 request packet) : 

; R - address of the UCB (unit control block) : 

: Outputs: : 

; RO - Ist longword of 1/0 status: contains status code and ‘ 

3 number of bytes transferred : 

3 R1 - 2nd longword of 1/0 status: device-dependent ° 


TDO_START: ; Process an 1/0 packet 
WFIKPCH TD_TIMEOUT,#TD_TIMEOUT_SEC 


; After a transfer completes successfully, return the number of bytes 
; transferred and a success status code. 
IOF ORK 
INSV UCB$W_BCNT(R5) ,#16,- ; Load number of bytes trans- 
: ferred into high word of RO. 
MOVW  § #SS$_NORMAL,RO ; Load a success code into RO. 


; Call 1/0 postprocessing. 


COMPLETE 10: 3; Driver processing is finished. 
QCOM 


TD_START = Start a transmit, receive, or set mode operation 
RE ; Complete 1/0. 
| 


: Device timeout handling. Return an error status code. 


TD_TIMEOUT: ; Timeout handling 
SETIPL UCBS$B_FIPL(RS) 3; Lower to driver fork IPL 
V2WL #SS$_TIMEOUT,RO ; Return error status. 
B OMPLETE_10 ; Call 1/0 postprocessing. 
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-SBTTL TD_INTERRUPT, Interrupt service routine 


++ 
TD_INTERRUPT, Analyzes interrupts, processes solicited interrupts 
Functional description: 

The sample code assumes either 


that the driver is for a single-unit controller, and 
that the unit initialization code has stored the 
address of the UCB in the IDB; or 


that the driver's start 1/0 routine acquired the 
controller's channel with a REQPCHANL macro call, and 
then invoked the WFIKPCH macro to keep the channel 
while waiting for an interrupt. 


; Inputs: 


oO 
~ 
uo 
v 
~ 
a 


pesater to the address of the IDB (interrupt data 
oc 


penrenene 
w 
o 
<— 
® 
a 
x 
r~ 


5 
saved PSL (program status longword) 
saved PC 


The IDB contains the CSR address and the UCB address. 
Outputs: 
The routine must preserve all registers except RO-R5. 


Service device interrupt 

Get address of IDB and remove 
ointer from stack. 

et address of device owner's 


Get address of device's CSR. 
If device does not expect 
interrupt, dismiss it. 


TD_INTERRUPT: 
MOVL @(SP)+,R4 


MOVL  § IDBSL_OWNER(R4) ,R5 
IDBSL_CSR(R4) .R4 
#UCBSV_INT,- 
UCBSW_STS(R5),- 
UNSOL~ INTERRUPT 


MOVL 
BBCC 


This is a solicited interrupt. Save 
the contents of the device registers in the UCB. 


MOVW TD_STATUS(R4),=- 3; Otherwise, save all device 
UCB$W_TD_STATUS(R5) ; registers. First the CSR. 


o 
we 
Cc 


oO 
wy 


— 
= 


PeSe Se Se Ge Be Ge Fe Se Se Se Se Se Se Se Se Se Se Se Se Se Se Se Se Se 


USER 
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| 
MOVW TD ete us Rohe - ; Save the word count register. | 
MOVW 1b BU UPAD ARGS - Sav the buffer address 


a 
og 
@ 
c 
nn” 
> 
oe 
» 
~~ 
@ 
“ww 
a 
i 


UCBSW regis 
MOVW Urabe tb pata - ; Save the’ data buffer register. 


RESTORE _DRIVER: ; Jump to main driver code. 
MOVL UCBSL_FR3(R5) ,R3 Restore driver's R3 (use a 
MOV to restore R3-R4). 
JSB @UCBSL_FPC(RS) Call driver at interrupt 
wait address. 


= 
oO 
sa 


: Restore control to the main driver. 


; Dismiss the interrupt. 


UNSOL_INTERRUPT: ; Dismiss unsolicited interrupt. 
POPR #*M<RO,R1,R2,R3,R4,R5> ; Restore RO-RS 
Return from interrupt. 


+ 
“+ 
- 


_— 
= 


o 
= 
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-SBTTL TO_CANCEL, Cancel 1/0 routine 


++ 
TD_CANCEL, Cancels an 1/0 operation in progress 
; Functional description: 


This routine calls IOCSCANCELIO to set the cancel bit in the 
UCB status word if: 


the device is busy 
the IRP's process {D matches the cancel process ID, 
the IRP channel matches the cancel channel. 


If IOCSCANCELIO sets the cancel bit, then this driver routine 
does device-dependent cancel 1/0 fixups. 


; Inputs: 


Ré = channel index number 

R - address of the current IRP (1/0 request packet) 

RG - address of the PCB (process control block) for the 
process comes l/ 

R5 - address of the UCB (unit control block) 

RB - cancel reason code, o 


ne of: 
CANSC_CANCEL if called through $CANCEL or 
SDALLOC system service 
CANSC_DASSGN if cpr ee through SDASSGN system 
service 

These reason codes are defined by the SCANDEF macro. 

; Outputs: 

The routine must preserve all registers except RO-R3. 


*he routine may set the UCBSM_CANCEL bit in UCBS$W_STS. 


Cancel an 1/0 operation | 

Set cancel bit if appropriate. 
If the cancel bit is not set, 
just return, 


TD_CANCEL: 
JSB G*1OCSCANCELIO 

BBC #UCBSV_CANCEL,- 
UCBSW_STS(R5) 108 


Device-dependent cancel operations go next. 


Finally, the return. 


RSB 3; Return 
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-SBTTL TD_REG_DUMP, Device register dump routine 


++ 
TD_REG_DUMP, Dumps the contents of device registers to a buffer 
Functional description: 


Writes the number of device registers, and their current 
contents into a diagnostic or error buffer. 


Inputs: 
RO - address of the output buffer 
RG - address of the CSR (controller status register) 
RS - address of the UCB (unit control block) 
Outputs: 


The routine must preserve all registers except R1-R3. 


The output buffer contains the current contents of the device 
registers. RO contains the address of the next empty longword in 
the output buffer. 


TD_REG_DUMP : ; Dump device registers 
MOV7ZBL #TD_NUM_REGS,(RO)+ ; Store device register count. 
MOVZWL UCBSU_TD_STATUS (RS) ,~ ; Store device status register. 
a 
MOVZWL YEEIE. FO UROCHTCRS) »= ; Store word count register. 
MOVZWL VCROM FO BUF ADR IRS) »= ; Store buffer address register. 
MOVZWL OEE Ty. FO BATEUF CRD) y= ; Store data buffer register. 
+ 


RSB 


; Return 


+f] 
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-SBTTL TDLEND, End of driver 


344 
; Label that marks the end of the driver 


TD_END: ; Last location in driver 
END 


. 
-* 
-* 
-@ 
-* 
-* 
-* 
-* 
:* 
-* 
-* 
:? 
-* 
® 
:@ 
-* 
2@ 
-* 
:* 
-* 
-* 
- 
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